/* tcpServer.h */

/************************************************************************************
*                    Copyright Aquantia Corporation
*                              Freeware
*
* Description:
*
*   This file defines all of the types and definitions used for the TCP Server
*
************************************************************************************/

/*! \file
    This file defines all of the types and definitions used for the TCP Server
*/

#ifndef AQ_TCP_SERVER_TOKEN
#define AQ_TCP_SERVER_TOKEN

#include "tcpServerProtocol.h"
#include <tcpServerConfig.h>
#include "sockets.h"

#include <stdint.h>


#ifdef __cplusplus
extern "C" {
#endif


/*! \addtogroup TCPServer TCP Server
This module contains the functions and data structures for the TCP server.  The message formats and commands are
listed below:
  
@{*/

/*! A structure used to track TCP sockets, their remote hostname, and their remote IP address and port */
typedef struct TCP_Socket_List
{
  unsigned int numberOfClients;                       /*!< The number of open TCP sockets */
  int socketID[MAX_NUMBER_OF_CLIENTS];                /*!< The array of open TCP socket handles */
  char* hostName[MAX_NUMBER_OF_CLIENTS];              /*!< The corresponding array of hostNames for each TCP socket. */
  char* ipAddress[MAX_NUMBER_OF_CLIENTS];             /*!< The corresponding array of IP addresses and ports for each TCP socket. */
} TCP_Socket_List;


/*! This function is designed to relay a TCP client message to the local hwInterace.  This function is defined in hwInterfaceServer.c
    Abstraction is done on the client side.
    \verbatim  Three compile definitions exist for this functions:

    1) BOARD_SUPPORT: this enables platform-level control of the adapter
    2) BLOCK_OPERATION_SUPPORT: this enables support for block operations
    3) LOCKING_AND_TRACKING_SUPPORT: this enables locking adapters and PHYs, as well as tracking multiple TCP clients simultaneously
                                     accessing local resources
                                     
    In addition to this, one run-time definition exists, which is support for block operations. The TCP server supports it by default,
    and if the local hardward supports, it then it is used for block operations, versus individual reads and writes

    At a bare minimum, the function requires the following from the local hwInterface:
      unsigned int HW_Fail ();
      char* HW_Error ();
      unsigned int HW_Initialize ();
      unsigned int HW_NumberOfDevices ();
      char** HW_DeviceList ();
      unsigned int HW_OpenAdapter (unsigned int adapter);
      unsigned int HW_CloseAdapter (unsigned int adapter);
      void HW_Close ();
      void HW_Write (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address, unsigned int data);
      unsigned int HW_Read (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address);
      unsigned int HW_GetDefaultAdapter ();
      unsigned int HW_SetDefaultAdapter (unsigned int adapter);
      unsigned int AQ_API_MDIO_SupportsBlockOperations ();

    Adding block operation support requires:
      unsigned int AQ_API_MDIO_MaxBlockOperations ();
      unsigned int HW_BlockReadAdapter (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address);
      void HW_BlockWriteAdapter (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address, unsigned int data);
      unsigned int* HW_BlockOperationExecuteAdapter (unsigned int adapter, unsigned int PHY_ID);
      unsigned int HW_BlockReadQueueSize ();

    Adding board support requires:
      void Board_WriteAdapter (unsigned int adapter, unsigned int address, unsigned int data);
      unsigned int Board_ReadAdapter (unsigned int adapter, unsigned int address);
    \endverbatim
    The following are a list of commands supported by the server:
    
\verbatim
  HW_Initialize

    Description: This command initializes the OS interface for the remote adapters, and returns information about
                 how many adapters there are and if it supports block operations.  It is required on some systems.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_Initialize

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Max Block Ops MSW     maxBlockOperations[15:8]: 0x0000 means no block operation support
    2               Max Block Ops LSW     maxBlockOperations[7:0]
    3               Byte indicating how many adapters are at this IP address
    4->NULL...      Series of null-terminated strings containing the adapter names in adapter order


  HW_OpenAdapter

    Description: This opens a remote adapter, and is required on some systems before talking to the PHYs.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_OpenAdapter
    1               Adapter Number        adapterNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Default Adapter       Default Adapter Number

  HW_CloseAdapter

    Description: This closes a remote adapter.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_CloseAdapter
    1               Adapter Number        adapterNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  HW_Close

    Description: This closes the OS interface to the remote adapters and is required on some systems.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_Close

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  HW_Write_Abstracted -> HW_Write at server

    Description: This writes data to the remote PHY.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_Write
    1               Adapter Number        adapterNumber
    2               PHY ID                phyNumber
    3               MMD                   MMD
    4               Address MSB           address[15:8]
    5               Address LSB           address[7:0]
    6               Data MSB              data[15:8]
    7               Data LSB              data[7:0]

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  HW_Read_Abstracted -> HW_Read at server

    Description: This reads data from the remote PHY.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_Read
    1               Adapter Number        adapterNumber
    2               PHY ID                phyNumber
    3               MMD                   MMD
    4               Address MSB           address[15:8]
    5               Address LSB           address[7:0]

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Data MSB              data[15:8]
    2               Data LSB              data[7:0]

  HW_BlockOperationExecuteAdapter

    Description: This sends a block of read and write operations to the remote PHY.  The block read and write
                 operations are stored at the client prior to execution.
    
  Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_BlockOperationExecuteAdapter
    1               Adapter Number        adapterNumber
    2               PHY ID                phyNumber
    3               # Of Operations MSB   numberOfOperations[15:8]
    4               # Of Operations MSB   numberOfOperations[7:0]
    5               Read/MMD              Read* / Write in Bit 7, MMD in 4:0
    6               Address MSB           address[15:8]
    7               Address LSB           address[7:0]
    [8]             Data MSB              data[15:8]
    [9]             Data LSB              data[7:0]
    .
    .
    .

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Number Of Reads MSB   numberOfReads[15:8]
    2               Number Of Reads LSB   numberOfReads[7:0]
    [3]             Data MSB              data[15:8]
    [4]             Data LSB              data[7:0]
    .
    .
    .

  Board_WriteAdapter

    Description: This writes data to the remote adapter or board control - i.e. for voltage margining, etc.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_Board_WriteAdapter
    1               Adapter #             adapterNumber
    2               Address MSB           address[15:8]
    3               Address LSB           address[7:0]
    4               Data MSB              data[15:8]
    5               Data LSB              data[7:0]

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  Board_ReadAdapter

    Description: This reads data from the remote adapter or board.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_Board_ReadAdapter
    1               Adapter #             adapterNumber
    2               Address MSB           address[15:8]
    3               Address LSB           address[7:0]

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Data MSB              data[15:8]
    2               Data LSB              data[7:0]

  HW_GetDefaultAdapter

    Description: This returns the number of the default adapter at the server.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_GetDefaultAdapter

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Adapter #             adapterNumber

  HW_SetDefaultAdapter

    Description: This sets the number of the default adapter at the server.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_SetDefaultAdapter
    1               Adapter #             adapterNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  Identify

    Description: This transmits the client's hostname to the server for use during debug - i.e. who has locked what
                 Also returns information whether server supports tracking and locking.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_Identify
    [1->NULL]       Client Name           The name of the client machine.  This is sent during connecting to the server
                                          for use during locking adapters and PHYs

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
    1               Board Support         1, if server supports board operations, 0 otherwise
    2               Tracking Support      1, if server supports tracking and locking, 0 otherwise

  HW_LockAdapter

    Description: This locks an adapter so that board reads and writes can only be executed by the locking socket ID.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_LockAdapter
    1               Adapter #             adapterNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  HW_UnlockAdapter

    Description: This unlocks an adapter.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_UnlockAdapter
    1               Adapter #             adapterNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  HW_LockPHY

    Description: This locks a PHY so that reads and writes to a PHY can only be executed by the locking socket ID.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_LockPHY
    1               Adapter #             adapterNumber
    2               PHY ID                phyNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length

  HW_UnlockPHY

    Description: This unlocks a PHY.
    
    Tx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Message Type          CODE_HW_UnlockPHY
    1               Adapter #             adapterNumber
    2               PHY ID                phyNumber

    Rx message format:

    Byte            Description           Value
    --------------------------------------------
    0               Error Flag            Set if there is an error
    [1->NULL]       Message               If no error, no message is provided and this has no length
\endverbatim
*/

unsigned int relayMessage
(
  const int currentSocketID_Index,  /*!< INPUT -  A pointer to the index in the TCP_Socket_List of the socket requesting the transaction */
  TCP_Socket_List* tcpSocketList,   /*!< INPUT - A pointer to the TCP_Socket_List structure used to track all open sockets               */
  uint8_t* RxBuffer,                /*!< INPUT -  A pointer to the incoming buffer containing a received message                         */
  int* RxBufferSize,                /*!< INPUT -  The size of the incoming buffer                                                        */
  uint8_t* TxBuffer,                /*!< OUTPUT - A pointer to the buffer containing the message response                                */
  int* TxBufferSize                 /*!< OUTPUT - The size of the outgoing buffer                                                        */
);


/*@}*/

#ifdef __cplusplus
}
#endif

#endif
